Repository navigation
feat(sync): live upload with transcribeLive() and openLive() - #177
Merged
Merged
Conversation
ccampbell-aai
force-pushed
the
ccampbell/node-sync-live
branch
from
September 10, 2026 17:12
71d0cde to
3cf564d
Compare
Port the Sync API live upload from the Python SDK. Both post to POST /v1/transcribe/stream with a hand-framed multipart body streamed as a chunked ReadableStream (duplex: "half"), config part first and always present, so the request starts before the audio exists and every speech segment but the last is transcribed while the caller is still recording. - client.sync.transcribeLive(audio, config?, options?) — pull-style, for sources that already are async iterables (Node streams included), sync iterables, or web ReadableStreams. Bytes, a Blob or a path are rejected by name, pointing at transcribe(). - client.sync.openLive(config?, options?) => SyncLiveSession — push-style, for callback-driven sources. write()/close()/result()/abort()/closed and a stream() WritableStream adapter. Exported from the package root with the SyncLiveAudioInput and SyncLiveOptions types. Node-specific handling, verified live against undici on Node 26: - The fetch timeout is a whole-request deadline (not per-operation as in httpx), so the live default is 180 s and must cover the recording; a hand-rolled deadlineSignal merges it with an optional caller signal without AbortSignal.any (Node 20+). - A producer error surfaces from fetch as an opaque "fetch failed"; the original is captured and rethrown unwrapped. - The server can reject mid-upload: fetch resolves with the status at once but withholds the body until the request body ends, so on a non-200 the SDK finishes the body itself rather than stream the rest of a rejected recording, and the error surfaces in ~150 ms instead of at the timeout. - session.write() after the session ends drops the chunk rather than throwing, so a capture callback outliving teardown cannot crash the process. This is the one deliberate divergence from the Python session. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- README: two collapsible blocks under the sync section — openLive() with a SoX microphone example, and transcribeLive() showing the on-disk-file anti-pattern versus a recorder stream, plus the shared caveats (overlap-only win, 120 s cap, silence abort, mid-upload errors, raw PCM fields). - CLAUDE.md: transcribeLive/openLive API bullets, a Live upload section, and a gotcha on the total-deadline timeout versus the 120 s audio cap. - New samples/sync-live-from-mic (SoX helper shared with the streaming sample). - CHANGELOG 4.39.0; version 4.38.0 -> 4.39.0. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
ccampbell-aai
force-pushed
the
ccampbell/node-sync-live
branch
from
September 10, 2026 17:12
3cf564d to
11d1cd2
Compare
ccampbell-aai
marked this pull request as ready for review
September 10, 2026 22:07
abort() guarded only on isAborted, so calling it after the request had already settled flipped isAborted and made a later result() throw the aborted error instead of returning the finished transcript. Guard on isSettled too, matching the documented "no-op once the request has completed" contract. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
aurpsis-aai
approved these changes
Sep 10, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds live upload to the Sync API: audio is uploaded while it is still being recorded, so every speech segment but the last is transcribed before the speaker stops. On a paced 7-second clip the wait after the last byte is roughly half that of the buffered
transcribe(), with a byte-identical transcript.API
client.sync.transcribeLive(audio, config?, options?)—audiois an async iterable (Node streams included), a sync iterable, or a webReadableStream<Uint8Array>. Same config and result type astranscribe(). Bytes, a Blob, or a path are rejected by name, pointing attranscribe().client.sync.openLive(config?, options?)→SyncLiveSession— for sources that deliver audio through a callback.write(chunk)queues audio (never blocks),close()ends it,result()resolves with the transcript,abort()drops the request,closedreports state, andstream()returns aWritableStreamso a web stream can be piped in. The request starts the moment the session opens.SyncLiveSession, and theSyncLiveAudioInput/SyncLiveOptionstypes.It posts
multipart/form-datatoPOST /v1/transcribe/live, streamed withTransfer-Encoding: chunkedso the request can start before the audio exists. Theconfigpart is sent first and is always present ({}when empty), which the endpoint requires.Behavior
options.timeout(default 180 s) is a whole-request deadline covering the recording as well as the transcription, andoptions.signalcancels the request. The Sync API still caps audio at 120 s.SyncTranscriptError, and can arrive part-way through the upload rather than only at the end.session.write()after the session has ended drops the chunk rather than throwing, so a capture callback that outlives teardown cannot crash the process. A non-bytes chunk still raises aTypeErrorat the call site.Tests
27 unit tests in
tests/unit/sync-live.test.tscover the body framing, config-first ordering, PCM, filename escaping, input rejections, mid-upload errors, and the full session lifecycle including abort and post-end writes. The full unit suite passes on Node 18 and 20 and across the httpx-free matrix;tsc, ESLint, Prettier, and publint are clean. A newsamples/sync-live-from-micrecords from the microphone and transcribes throughopenLive().🤖 Generated with Claude Code